﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>Hotstring - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The Hotstring function creates, modifies, enables, or disables a hotstring while the script is running." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Hotstring</h1>

<p>在脚本运行时创建, 修改, 启用或禁用<a href="../Hotstrings.htm">热字串</a>.</p>

<pre class="Syntax"><span class="func">Hotstring</span> String <span class="optional">, Replacement, OnOffToggle</span>
<span class="func">Hotstring</span> <a href="#NewOptions">NewOptions</a>
<span class="func">Hotstring</span> <a href="#SubFunctions">SubFunction</a> <span class="optional">, Value1</span></pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>String</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>热字串的触发字符串, 前面是<a href="../Hotstrings.htm">常用的冒号对</a>和<a href="../Hotstrings.htm#Options">选项字符</a>. 例如, <code>"::btw"</code> 或 <code>":*:]d"</code>.</p>
    <p><em>String</em> 可以考虑通过<a href="../Hotstrings.htm#C">区分大小写(C)</a>, <a href="../Hotstrings.htm#Question">单词敏感性(?)</a>, 激活条件(如 <a href="_HotIf.htm">#HotIf</a> 或 <a href="HotIf.htm">HotIf</a> 设置) 和触发字符串来匹配现有的热字符串. 例如, <code>"::btw"</code> 和 <code>"::BTW"</code> 只有在区分大小写模式作为默认值开启时才匹配, 而 <code>":C:btw"</code> 和 <code>":C:BTW"</code> 永远不匹配. <code>C</code> 和 <code>?</code> 选项可能包含在 <em>String</em> 中, 也可以通过 <a href="_Hotstring.htm">#Hotstring</a> 指令或之前使用的 <em>NewOptions</em> 设为默认值.</p>
    <p>如果热字串已经存在, 那么在 <em>String</em> 中指定的所有选项都会生效, 而其他所有选项都保持原样. 但是, 由于带有 <code>C</code> 或 <code>?</code> 的热字串被认为是与其他热字串不一样的, 所以不可能添加或删除这些选项. 作为代替, 关闭现有热字串并创建一个新的.</p>
    <p>当热字串第一次被创建时 -- 无论是通过热字串函数还是脚本中的<a href="../Hotstrings.htm">双冒号语法</a> -- 其触发字符串和选项字符序列都将成为热字串的固定名称, 正如 <a href="../Hotstrings.htm#ThisHotkey">ThisHotkey</a> 中显示的名称. 即使热字串函数稍后使用不同的选项字符访问热字串, 这个名称也不会改变.</p>
  </dd>

  <dt>Replacement</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a>或<a href="../misc/Functor.htm">函数对象</a></p>
    <p>如果省略, 并且 <em>String</em> 已经作为热字串存在, 则不会更改其替换. 这用于只更改热字串的选项, 或打开或关闭热字串. 否则, 请指定替换字符串或回调.</p>
    <p>如果 <em>Replacement</em> 是一个函数, 则在热字串触发时调用它(作为一个新<a href="../misc/Threads.htm">线程</a>).</p>
    <p>回调函数接受一个参数, <a href="../Functions.htm#intro">定义</a>如下:</p>
    <pre class="NoIndent">MyCallback(HotstringName) { ...</pre>
    <p>尽管您给参数的名称并不重要, 但它被赋值为<a href="../Hotstrings.htm#ThisHotkey">热字串的名称</a>.</p>
    <p>如果不需要相应的信息, 可以省略回调参数, 但在这种情况下必须指定星号, 例如 <code>MyCallback(*)</code>.</p>
    <p><a href="../Hotstrings.htm">双冒号语法</a>定义的热字串自动使用参数名称 <code>ThisHotkey</code>. 也可以在没有 Hotstring 函数的情况下, 为热字串<a href="../Hotstrings.htm#Function">指定一个函数名</a>.</p>
    <p>在重新指定热字符串的函数后, 只有在<a href="../Hotstrings.htm#Function">给定名称</a>的情况下, 才能恢复其原始函数.</p>
    <p class="note"><strong>注意:</strong> 如果指定了这个参数, 但是由于之前使用此函数而禁用了热字串, 那么热字串将继续禁用. 为了避免这种情况, 请为 <em>OnOffToggle</em> 指定 <code>"On"</code>.</p>
  </dd>

  <dt>OnOffToggle</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>下列值之一:</p>
    <p><strong>On</strong> 或 <strong>1</strong>(true): 启用热字串.</p>
    <p><strong>Off</strong> 或 <strong>0</strong>(false): 禁用热字串.</p>
    <p><strong>Toggle</strong> 或 <strong>-1:</strong> 设置热字串到相反的状态(启用或禁用).</p>
  </dd>

  <dt>NewOptions</dt>
  <dd id="NewOptions">
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>要为随后创建的热字串设置新的默认选项, 请将这些选项传递给 Hotstring 函数, 不带任何前导或尾随冒号. 例如: <code>Hotstring "T"</code>.</p>
    <p>打开<a href="../Hotstrings.htm#C">大小写敏感(C)</a> 或<a href="../Hotstrings.htm#Question">单词敏感(?)</a> 也会影响对 Hotstring 函数的任何后续调用将找到哪些现有的热字符串. 例如, 默认情况下, <code>Hotstring ":T:btw"</code> 会找到 <code>::BTW</code>, 但如果 <code>Hotstring "C"</code> 或 <code><a href="_Hotstring.htm">#Hotstring</a> C</code> 生效时, 则不会. 这可以通过传递互斥选项来撤消或重写; 例如, <code>C0</code> 和 <code>C1</code> 覆盖 <code>C</code>.</p>
  </dd>

  <dt>SubFunction, Value1</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>这些参数相互依赖, 它们的用法如下所述.</p>
  </dd>

</dl>

<h2 id="SubFunctions">子函数</h2>
<p>对于 <em>SubFunction</em>, 指定以下参数之一:</p>
<ul>
  <li><a href="#EndChars">EndChars</a>: 检索或修改结束字符集.</li>
  <li><a href="#MouseReset">MouseReset</a>: 控制鼠标点击是否重置热字串识别器.</li>
  <li><a href="#Reset">Reset</a>: 立即复位热字串识别器.</li>
</ul>

<h3 id="EndChars">EndChars</h3>
<p>检索或修改由热字串识别器用作<a href="../Hotstrings.htm#EndChars">终止符</a>的字符集.</p>
<pre class="Syntax">OldValue := <span class="func">Hotstring</span>("EndChars" <span class="optional">, NewValue</span>)</pre>
<p>例如:</p>
<pre>prev_chars := Hotstring("EndChars", "-()[]{}':;`"/\,.?!`n`s`t")
MsgBox "The previous value was: " prev_chars</pre>
<p><a href="#EndChars">#Hotstring EndChars</a> 也会影响这个设置.</p>
<p>目前不能为每一个热字串指定不同的终止符字符集.</p>

<h3 id="MouseReset">MouseReset</h3>
<p>检索或修改全局设置, 该设置控制鼠标单击是否重置热字串识别器, 如<a href="../Hotstrings.htm#NoMouse">这里</a>所描述的那样.</p>
<pre class="Syntax">OldValue := <span class="func">Hotstring</span>("MouseReset" <span class="optional">, NewValue</span>)</pre>
<p><em>NewValue</em> 为 1(true) 以启用鼠标点击检测和重置热字串识别器, 或者 0(false) 来禁用. 返回值是在调用函数之前生效的设置.</p>
<p>如果此函数所做的更改有需要, 将安装或删除<a href="_InstallMouseHook.htm">鼠标</a>钩子.</p>
<p><a href="_Hotstring.htm">#Hotstring NoMouse</a> 也会影响此设置, 等同于将 <em>NewValue</em> 指定为 <code>false</code>.</p>

<h3 id="Reset">Reset</h3>
<p>立即重置热字串识别器.</p>
<pre class="Syntax"><span class="func">Hotstring</span> "Reset"</pre>
<p>换句话说, 脚本将开始等待一个全新热字串, 不再考虑之前键入的任何内容.</p>

<h2 id="Errors">错误</h2>
<p>如果参数无效或内存分配失败, 则函数抛出 <a href="Error.htm#TargetError">TargetError</a>.</p>
<p>如果省略了 <em>Replacement</em> 并且 <em>String</em> 有效但无法匹配到一个存在的热字串, 则也会抛出异常. 这可以用来测试热字串的存在. 例如:</p>
<pre>try
    Hotstring "::btw"
catch TargetError
    MsgBox "The hotstring does not exist or it has no variant for the current HotIf criteria."</pre>

<h2 id="Remarks">备注</h2>
<p><a href="HotIf.htm">当前 HotIf 设置</a>决定了哪一个热字串函数的<a href="#variant">变体</a>将会运行.</p>
<p>如果该脚本被<a href="Suspend.htm">挂起</a>, 新添加/启用的热字串也将挂起, 直到挂起关闭(<a href="Suspend.htm">Suspend</a> 页面中所描述的豁免除外).</p>
<p>如果此函数所做的更改有需要, 将安装或删除<a href="InstallKeybdHook.htm">键盘</a>和/或<a href="InstallMouseHook.htm">鼠标</a>钩子.</p>
<p>此函数不能直接启用或禁用本身以外的脚本中的热字串.</p>
<p>一旦脚本具有至少一个热字符串, 它将成为<a href="../Scripts.htm#persistent">持续运行的</a>脚本, 这意味着应该使用 <a href="ExitApp.htm">ExitApp</a> 而不是 <a href="Exit.htm">Exit</a> 来退出(终止) 脚本.</p>

<h2 id="variant">变体(副本) 热字串</h2>
<p>一个特定的热字符串可以创建多次, 如果每个定义具有不同的 <a href="HotIf.htm">HotIf</a> 条件, <a href="../Hotstrings.htm#C">区分大小写</a>(<code>C</code> vs. <code>C0</code>/<code>C1</code>), 或<a href="../Hotstrings.htm#Question">单词敏感性</a>(<code>?</code>). 这些被称为 <em>热字串变体</em>. 例如:</p>
<pre>HotIfWinActive "ahk_group CarForums"
Hotstring "::btw", "behind the wheel"
HotIfWinActive "Inter-Office Chat"
Hotstring "::btw", "back to work"
HotIfWinActive
Hotstring "::btw", "by the way"</pre>
<p>如果一个热字串的多个变体能被触发, 那么只有最早创建的将会触发.</p>
<p>有关详情, 请参阅 <a href="HotIf.htm">HotIf</a>.</p>

<h2 id="Related">相关</h2>
<p><a href="../Hotstrings.htm">热字串</a>, <a href="_HotIf.htm">#HotIf</a>, <a href="../Variables.htm#ThisHotkey">A_ThisHotkey</a>, <a href="_MaxThreadsPerHotkey.htm">#MaxThreadsPerHotkey</a>, <a href="Suspend.htm">Suspend</a>, <a href="../misc/Threads.htm">线程</a>, <a href="Thread.htm">Thread</a>, <a href="Critical.htm">Critical</a></p>

<h2 id="Examples">示例</h2>

<div class="ex" id="ExHelper">
<p><a class="ex_number" href="#ExHelper"></a> 热字串助手. 如果您是一个热字串重度用户, 下面的脚本可能会很有用. 它基于 Andreas Borutta 创建的 v1 脚本. 通过按下 <kbd>Win</kbd>+<kbd>H</kbd>(或您选择的其他热键), 可以将当前选定的文本转换为热字串. 例如, 如果您在文字处理软件中选择了 "by the way", 按下 <kbd>Win</kbd>+<kbd>H</kbd> 会提示您输入其缩写(例如 btw), 然后将新热字串添加到脚本中并启用它.</p>
<pre>#h::  <em>; Win+H 热键</em>
{
    <em> 获取当前选择的文本. 使用剪贴板代替
    ; EditGetSelectedText 是因为它可以工作于更大范围的编辑器
    ; (即文字处理软件).  保存剪贴板当前的内容
    ; 以便在后面恢复. 尽管只能处理纯文本,
    ; 但总比没有好:</em>
    ClipboardOld := A_Clipboard
    A_Clipboard := "" <em>; 必须清空, 才能检测是否有效.</em>
    Send "^c"
    if !ClipWait(1)  <em>; ClipWait 超时.</em>
    {
        A_Clipboard := ClipboardOld <em>; 恢复剪贴板之前的内容.</em>
        return
    }

    <em>; 替换 CRLF 和/或 LF 为 `n 以便用于 "send-raw" 热字串:
    ; 对其他任何在原始模式下可能出现问题
    ; 的字符进行相同的处理:</em>
    ClipContent := StrReplace(A_Clipboard, "``", "````")  <em>; 首先进行此替换以避免和后面的操作冲突.</em>
    ClipContent := StrReplace(ClipContent, "`r`n", "``n")
    ClipContent := StrReplace(ClipContent, "`n", "``n")
    ClipContent := StrReplace(ClipContent, "`t", "``t")
    ClipContent := StrReplace(ClipContent, "`;", "```;")
    A_Clipboard := ClipboardOld  <em>; 恢复剪贴板之前的内容.</em>
    ShowInputBox(":T:`::" ClipContent)
}

ShowInputBox(DefaultValue)
{
    <em>; 这里会移动输入框的光标到更人性化的位置:</em>
    SetTimer MoveCaret, 10
    <em>; 显示输入框, 提供默认的热字串:</em>
    IB := InputBox("
    (
    Type your abreviation at the indicated insertion point. You can also edit the replacement text if you wish.

    Example entry: :T:btw`::by the way
    )", "New Hotstring",, DefaultValue)
    if IB.Result = "Cancel"  <em>; 用户选择了取消.</em>
        return

    if RegExMatch(IB.Value, "(?P&lt;Label&gt;:.*?:(?P&lt;Abbreviation&gt;.*?))::(?P&lt;Replacement&gt;.*)", &amp;Entered)
    {
        if !Entered.Abbreviation
            MsgText := "You didn't provide an abbreviation"
        else if !Entered.Replacement
            MsgText := "You didn't provide a replacement"
        else
        {
            Hotstring Entered.Label, Entered.Replacement  <em>; 现在激活热字串.</em>
            FileAppend "`n" IB.Value, A_ScriptFullPath  <em>; 保存热字串以备以后使用.</em>
        }
    }
    else
        MsgText := "The hotstring appears to be improperly formatted"

    if IsSet(MsgText)
    {
        Result := MsgBox(MsgText ". Would you like to try again?",, 4)
        if Result = "Yes"
            ShowInputBox(DefaultValue)
    }
    
    MoveCaret()
    {
        WinWait "New Hotstring"
        <em>; 否则移动输入框中的光标到用户输入缩写的位置.</em>
        Send "{Home}{Right 3}"
        SetTimer, 0
    }
}</pre>
</div>

</body>
</html>